---
title: 통합 추가
description: Astro 프로젝트에 통합을 추가하는 방법을 알아보세요.
sidebar:
  label: 통합 개요
i18nReady: true
---
import IntegrationsNav from '~/components/IntegrationsNav.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import { Steps } from '@astrojs/starlight/components';

**Astro 통합**은 단 몇 줄의 코드만으로 프로젝트에 새로운 기능과 동작을 추가합니다. 공식 통합, [커뮤니티 통합](#더-많은-통합-찾기) 또는 심지어 [사용자 정의 통합을 구축](#나만의-통합-구축)할 수도 있습니다.

통합은 다음을 수행할 수 있습니다.

- [렌더러](/ko/guides/framework-components/)를 사용하여 React, Vue, Svelte, Solid 및 다른 인기 있는 UI 프레임워크를 잠금 해제합니다.
- [SSR 어댑터](/ko/guides/on-demand-rendering/)로 주문형 렌더링을 활성화합니다.
- 몇 줄의 코드만으로 MDX 및 Partytown과 같은 도구를 추가합니다.
- 자동 사이트맵 생성과 같은 새로운 기능을 프로젝트에 추가합니다.
- 빌드 프로세스, 개발 서버 등에 연결되는 사용자 정의 코드를 작성합니다.

:::tip[통합 디렉터리]
[통합 디렉터리](https://astro.build/integrations/)에서 수백 개의 공식 및 커뮤니티 통합의 전체 세트를 살펴보거나 검색하세요. 인증, 분석, 성능, SEO, 접근성, UI, 개발자 도구 등을 위해 Astro 프로젝트에 추가할 패키지를 찾아보세요.
:::

## 공식 통합

다음 통합은 Astro에서 유지 관리합니다.

<IntegrationsNav />

## 자동 통합 설정

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 이 명령을 사용하여 여러 커뮤니티 플러그인을 추가할 수도 있습니다. `astro add`가 지원되는지 또는 [수동으로 설치](#수동-설치)해야 하는지 확인하려면 각 통합의 문서를 확인하세요.

선택한 패키지 관리자를 사용하여 `astro add` 명령을 실행하면 자동 통합 마법사가 구성 파일을 업데이트하고 필요한 종속성을 설치합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro add react
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro add react
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro add react
  ```
  </Fragment>
</PackageManagerTabs>

동시에 여러 통합을 추가하는 것도 가능합니다!

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro add react sitemap partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro add react sitemap partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro add react sitemap partytown
  ```
  </Fragment>
</PackageManagerTabs>

:::note[통합 종속성 처리]
통합을 추가한 후 `Cannot find package '[package-name]'`과 같은 경고가 표시되면 패키지 관리자가 [피어 종속성](https://nodejs.org/en/blog/npm/peer-dependencies/)을 설치하지 않았을 수 있습니다. 누락된 패키지를 설치하려면 다음 명령을 실행하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install [package-name]
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add [package-name]
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add [package-name]
  ```
  </Fragment>
</PackageManagerTabs>
:::

### 수동 설치

Astro 통합은 항상 `astro.config.mjs` 파일의 `integrations` 속성을 통해 추가됩니다.

Astro 프로젝트로 통합을 가져오는 세 가지 일반적인 방법이 있습니다.

1. [npm 패키지로 통합을 설치](#npm-패키지-설치)합니다.
2. 프로젝트의 로컬 파일에서 자체 통합을 가져옵니다.
3. 구성 파일에 직접 통합 인라인을 작성합니다.

    ```js
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import installedIntegration from '@astrojs/vue';
    import localIntegration from './my-integration.js';

    export default defineConfig({
      integrations: [
        // 1. 설치된 npm 패키지에서 가져옵니다.
        installedIntegration(),
        // 2. 로컬 JS 파일에서 가져옵니다.
        localIntegration(),
        // 3. 인라인 객체를 작성합니다.
        {name: 'namespace:id', hooks: { /* ... */ }},
      ]
    });
    ```

통합을 작성할 수 있는 다양한 방법을 모두 알아보려면 [통합 API](/ko/reference/integrations-reference/) 참조를 확인하세요.

#### NPM 패키지 설치

패키지 관리자를 사용하여 NPM 패키지 통합을 설치한 다음 `astro.config.mjs`를 수동으로 업데이트하세요.

예를 들어 `@astrojs/sitemap` 통합을 설치하려면 다음을 수행하세요.

<Steps>
1. 원하는 패키지 관리자를 사용하여 프로젝트 종속성에 대한 통합을 설치합니다.

   <PackageManagerTabs>
     <Fragment slot="npm">
     ```shell
     npm install @astrojs/sitemap
     ```
     </Fragment>
     <Fragment slot="pnpm">
     ```shell
     pnpm add @astrojs/sitemap
     ```
     </Fragment>
     <Fragment slot="yarn">
     ```shell
     yarn add @astrojs/sitemap
     ```
     </Fragment>
   </PackageManagerTabs>

2. 통합을 `astro.config.mjs` 파일로 가져와 구성 옵션과 함께 `integrations[]` 배열에 추가합니다.

    ```js title="astro.config.mjs" ins={2} ins="sitemap()"
    import { defineConfig } from 'astro/config';
    import sitemap from '@astrojs/sitemap';

    export default defineConfig({
      // ...
      integrations: [sitemap()],
      // ...
    });
    ```

    통합마다 구성 설정이 다를 수 있습니다. 각 통합의 문서를 읽고 `astro.config.mjs` 파일에서 선택한 통합에 필요한 구성 옵션을 적용하세요.
</Steps>

### 맞춤 옵션

통합은 대부분의 경우 실제 통합 객체를 반환하는 팩토리 함수로 작성됩니다. 이를 통해 프로젝트 통합을 사용자 정의하는 팩토리 함수에 인수와 옵션을 전달할 수 있습니다.

```js
integrations: [
  // 예: 함수 인수를 사용하여 통합 사용자 정의
  sitemap({filter: true})
]
```

### 통합 켜고 끄기

거짓같은 값을 나타내는 통합은 무시되므로 `undefined` 및 부울 값을 신경쓰지 않고 통합을 켜거나 끌 수 있습니다.

```js
integrations: [
  // 예: Windows에서 사이트맵 작성 건너뛰기
  process.platform !== 'win32' && sitemap()
]
```

## 통합 업그레이드

모든 공식 통합을 한 번에 업그레이드하려면 `@astrojs/upgrade` 명령을 실행하세요. 그러면 Astro와 모든 공식 통합이 최신 버전으로 업그레이드됩니다.

### 자동 업그레이드

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # Astro와 공식 통합을 최신 버전으로 함께 업그레이드
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # Astro와 공식 통합을 최신 버전으로 함께 업그레이드
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # Astro와 공식 통합을 최신 버전으로 함께 업그레이드
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>

### 수동 업그레이드

하나 이상의 통합을 수동으로 업그레이드하려면 패키지 관리자에 적합한 명령을 사용하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 예: React 및 Partytown 통합 업그레이드
  npm install @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 예: React 및 Partytown 통합 업그레이드
  pnpm add @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 예: React 및 Partytown 통합 업그레이드
  yarn add @astrojs/react@latest @astrojs/partytown@latest
  ```
  </Fragment>
</PackageManagerTabs>

## 통합 제거

<Steps>
1. 통합을 제거하려면 먼저 프로젝트에서 통합을 제거하세요.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm uninstall @astrojs/react
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm remove @astrojs/react
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn remove @astrojs/react
      ```
      </Fragment>
    </PackageManagerTabs>

2. 그런 다음 `astro.config.*` 파일에서 통합을 제거합니다.

    ```js title="astro.config.mjs" del={3,7}
    import { defineConfig } from 'astro/config';

    import react from '@astrojs/react';

    export default defineConfig({
      integrations: [
        react()
      ]
    });
    ```
</Steps>

## 더 많은 통합 찾기

[Astro 통합 디렉터리](https://astro.build/integrations/)에서 커뮤니티에서 개발한 다양한 통합을 찾을 수 있습니다. 자세한 사용법 및 구성 지침을 보려면 해당 링크를 따르세요.

## 나만의 통합 구축

Astro의 통합 API는 Rollup 및 Vite에서 영감을 얻었으며, 이전에 Rollup 또는 Vite 플러그인을 작성한 적이 있는 모든 사람에게 친숙하게 느껴지도록 설계되었습니다.

통합이 수행할 수 있는 작업과 직접 작성하는 방법을 알아보려면 [통합 API](/ko/reference/integrations-reference/) 참조를 확인하세요.
